<html>
<head>
<title>ModelFactory howto: 50 ways to make your models</title>
<link href="../styles/doc.css" rel="stylesheet" type="text/css">
</head>
<body>

<h1>50 ways to make your models</h1>

<b>author</b>: Chris Dollin
<br><b>version</b>: 1.2, Jena 2.5+, January 2007 

<h1>introduction</h1>

Jena has become a moderately complicated system, with several different kinds
of <code>Model</code> and ways of constructing them. This note describes the
Jena 2 <code>ModelFactory</code>, your one-stop shop for creating Jena models.
<code>ModelFactory</code> lives in <code>com.hp.hpl.jena.rdf.model</code>,
which you will import anyway to do anything with models.

<p>Most of <code>ModelFactory</code> methods have been around for a while now,
but Jena 2.5's ModelFactory contains methods that use the <code>Assembler</code>
API which appeared in Jena 2.4, which allows models to be created according 
to RDF descriptions that can be programmatically constructed or read in from 
external resources such as configuration files. 
(This API replaces the old 
<code>ModelSpec</code> API, which had proved unsatisfactory.)

<p>This note is an introduction, not an exhaustive description. As usual
consult the Javadoc for details of the methods and classes to use.

<h1>simple model creation</h1>

The simplest way to create a model (if not the shortest) is to call
<code>ModelFactory.createDefaultModel()</code>. This [by default] delivers a
plain RDF model, stored in-memory, that does no inference and has no special
ontology interface.

<h1>ModelMakers</h1>

Plain models can be given names which allows them to be "saved" and looked up by
name later. This is handled by implementations of the interface
<code>ModelMaker</code>; each <code>ModelMaker</code> produces Models of the
same kind. The simplest kind of <code>ModelMaker</code> is a memory model
maker, which you get by calling
<code>ModelFactory.createMemModelMaker()</code>. The methods you'd want to use
to start with on a ModelMaker are:

<ul>

<li><code>createModel(String)</code>: create a model with the given name in
the ModelMaker. If a model with that name already exists, then that model is
used instead.

<li><code>openModel(String)</code>: open an existing model with the given
name. If no such model exists, create a new empty one and give it that name.

[createModel(String) and openModel(String) behave in the same way, but each
has a two-argument form for which the behaviour is different. Use whichever
one best fits your intention.]

<li><code>createModel()</code>: create a fresh anonymous model.

<li><code>getModel()</code>: each <code>ModelMaker</code> has a <i>default
model</i>; this method returns that model.

</ul>

There are other methods, for removing models, additional control over create
<i>vs</i> open, closing the maker, and looking names up; for those consult the
<a href="../javadoc/com/hp/hpl/jena/rdf/model/ModelMaker.html">ModelMaker
javadoc</a>.

<h2>file-based models</h2>

The method <code>ModelFactory.createFileModelMaker(String)</code> returns a
<code>ModelMaker</code> which attaches models to filing-system files. The
<code>String</code> argument is the <i>fileBase</i>. When a file-ModelMaker
opens a file, it reads it from a file in the directory named by the fileBase;
when the model is closed (and <i>only</i> then, in the current
implementation), the contents of the model are written back to the file.

<p>Because the names of models in a modelMaker can be arbitrary character
strings, in particular URIs, they are translated slightly to avoid confusion
with significant characters of common filing systems. In the current
implementation,

<ul>
<li> colon : is converted to _C
<li> slash / is converted to _S
<li> underbar _ is converted to _U
</ul>

<h1>reification styles</h1>

Jena models have different <i>reification styles</i>, which are described in
more detail in the <a href="reification.html">reification howto</a>.
<code>ModelFactory</code> provides constants for those styles:

<ul>
<li><code>ModelFactory.Standard</code>
<li><code>ModelFactory.Convenient</code>
<li><code>ModelFactory.Minimal</code>
</ul>

And methods corresponding to those already discussed:

<ul>

<li><code>ModelFactory.createDefaultModel(style)</code> creates a default
    model with the specified reification style.

<li><code>ModelFactory.createMemModelMaker(style)</code> creates a ModelMaker
    that creates memory models with the specified reification style.

<li><code>ModelFactory.createFileModelMaker(root,style)</code></li> creates
    a ModelMaker that creates file-associated models with the specified reification
    style.
</ul>

Reification styles also appear in other Modelfactory methods, although they are
not required. We shall not discuss them further in this document; consult the
Javadoc for appropriate details.

<h1>database model creation</h1>

Jena allows models to be created within databases. For an extensive discussion
of the available options and controls, see the <a href="../DB/index.html">database
howto documents</a>. The current ModelFactory interface only provides simple
access to database model creation.

<p>ModelFactory creation of models takes place through RDB ModelMakers:

<ul>
<li><code>createModelRDBMaker(IDBConnection c)</code></li>
</ul>

delivers a ModelMaker that makes (or finds) models by name in the Jena model
database attached to the connection <code>c</code>. Models from an RDB maker
are "just like" memory-based models, except that they can be much larger, are
likely to be significantly slower, and persist over application termination.

<p>The connection can be created in two ways:

<ul>
<li><code>ModelFactory.createSimpleRDBConnection(url,user,pass,type)</code>:
    creates a connection to the database with the given JDBC url, the given user
    and password, and the database type.

<li><code>ModelFactory.createSimpleRDBConnection()</code>: creates
    a connection to the database, taking the URL from the system property <b>jena.db.url</b>,
    the user name from <b>jena.db.user</b>, the password from <b>jena.db.password</b>,
    and the database type from <b>jena.db.type</b>.
</ul>

Details of these fields can be found in the database documentation, as well as
direct ways to construct connections if required, and additional operations on
RDB Models that may be useful.

<h1>legacy DAML models</h1>

The method <code>createDAMLModel()</code> creates a DAML Model using the
legacy DAML interface. <i>This method is only provided for backward compatability.
</i> New development should use the Ontology API and OWL instead of DAML.
We strongly encourage users to switch from the legacy API.

<h1>inference model creation</h1>

An important feature of Jena 2 is support for different kinds of inference over
RDF-based models (used for RDFS, OWL, and DAML). Inference models are constructed
by applying <i>reasoners</i> to <i>base models</i> and optionally <i>schema</i>.
The statements deduced by the reasoner from the base model then appear in the
inferred model alongside the statements from the base model itself.

<p>RDFS reasoning is directly available:

<ul>
<li><code>createRDFSModel(Model base)</code> creates an inference model over the
    base model using the built-in RDFS inference rules and any RDFS statements
    in the base model.

<li><code>createRDFSModel(Model schema, Model base)</code> creates an RDFS
    inference model from the base model and the supplied schema model. The advantage
    of supplying the schema separately is that the reasoner may be able to compute
    useful information in advance on the assumption that the schema won't change,
    or at least not change as often as the base model.
</ul>

It's possible to use other reasoning systems than RDFS. For these a Reasoner is
required:

<ul>
<li><code>createInfModel(Reasoner reasoner, Model base)</code> creates
    an inference model using the rules of <code>reasoner</code> over the
    model <code>base</code>.

<li><code>createInfModel(Reasoner reasoner, Model schema, Model base)</code>
    Just as for the RDFS case, the schema may be supplied separately to allow the
    reasoner to digest them before working on the model.
</ul>

Ah, but from where do you fetch your reasoners? From the <i>reasoner registry</i>,
the class <a href="../javadoc/com/hp/hpl/jena/reasoner/ReasonerRegistry.html">
ReasonerRegistry</a>. This allows reasoners to be looked up by name, but also
provides some predefined access methods for well-know reasoners:

<ul>
<li><code>getOWLReasoner()</code>: the reasoner used for OWL inference

<li><code>getRDFSReasoner()</code>: the reasoner used for RDFS inference

<li><code>getTransitiveReasoner()</code>: a reasoner for doing subclass and
    supproperty closure.
</ul>


<h1>ontology model creation</h1>

An <i>ontology model</i> is one that presents RDF as an ontology - classes,
individuals, different kinds of properties, and so forth. Jena supports RDFS, OWL,
and DAML ontologies through <i>profiles</i>. There is extensive documentation
on <a href="../ontology/index.html">Jena's ontology support</a>, so all we'll
do here is summarise the creation methods.

<ul>
<li><code>createOntologyModel()</code> Creates an ontology model
    which is in-memory and presents OWL ontologies.

<li><code>createOntologyModel(OntModelSpec spec, Model base)</code> Creates an
    ontology model according the <a href="../javadoc/com/hp/hpl/jena/ontology/OntModelSpec.html">
    OntModelSpec</a> <code>spec</code> which presents the ontology of <code>base</code>.

<li><code>createOntologyModel(OntModelSpec spec, ModelMaker maker, Model base)</code>
    Creates an OWL ontology model according to the <code>spec</code> over the
    <code>base</code> model. If the ontology model needs to construct additional
    models (for OWL imports), use the <code>ModelMaker</code> to create them.
    [The previous method will construct a <code>MemModelMaker</code> for this.]

</ul>

And where do <code>OntModelSpec</code>s come from? There's a cluster of constants
in the class which provide for common uses; to name but three:

<ul>
<li><code>OntModelSpec.OWL_MEM_RDFS_INF</code> OWL ontologies, model stored
    in memory, using RDFS entailment only

<li><code>OntModelSpec.RDFS_MEM</code> RDFS ontologies, in memory, but doing
    no additional inferences

<li><code>OntModelSpec.OWL_DL_MEM_RULE_INF</code> OWL ontologies, in memory,
    with the full OWL Lite inference
</ul>

<h1>creating models from Assembler descriptions</h1>

A new feature of Jena since Jena 2.4 is the use of <i>assembler
descriptions</i>, documented in the
<a href="../assembler/assembler-howto.html">assembler howto</a>.
Access to the assembler system for model creation is provided
by three ModelFactory methods:

<ul>
<li><code>assembleModelFrom( Model singleRoot )</code>: assemble
    a Model from the single Model description in <code>singleRoot</code>.
    If there is no such description, or more than one, an exception
    is thrown. If a description has to be selected from more than
    one available candidates, consider using the methods below.

<li><code>findAssemblerRoots( Model m )</code>: answer a Set
    of all the Resources in <code>m</code> which are of type
    <code>ja:Model</code>, ie descriptions of models to assemble.
    (Note that this will include sub-descriptions of embedded
    models if they are present.)

<li><code>assembleModelFrom( Resource root )</code>: answer
    a Model assembled according to the description hanging
    from <code>root</code>. 
</ul>

<p>Assemblers can construct other things as well as models,
and the Assembler system is user-extensible: see the howto
for details.

<h1>Hodgepodge</h1>

Finally, <code>ModelFactory</code> contains a hodgepodge of methods
for some special cases not conveniently dealt with elsewhere.

<p><code>createModelForGraph(Graph g)</code> is used when an advanced
user with access to the Jena SPI has constructed or obtained a <code>Graph</code>
and wishes to present it as a model. This method wraps the graph up as
a plain model. Alterations to the graph are visible in the model, and
<i>vice versa</i>.

<p><code>withHiddenStatements(Model)</code> returns a new Model in which
any reification quadlets (see the reification howto) that may be hidden
in the base model are exposed in the result. It may return the base model,
if it does not hide quadlets. This is useful if you want to see all the
statements of the model as they will appear in a serialisation.

</body>
</html>
